home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / cmdline.lha / cmdline / Overview < prev    next >
Text File  |  1993-04-13  |  11KB  |  260 lines
  1.  
  2.  
  3.                     An overview of CmdLine and cmdparse
  4.                     ===================================
  5.  
  6.                  by Brad Appleton <brad@ssd.csd.harris.com>
  7.  
  8.  
  9.  
  10.  Introduction
  11.  ------------
  12.  CmdLine is a C++ Library for parsing command-line arguments. It is 
  13.  approximately 2000 lines of C++ code (excluding comments).
  14.  
  15.  Cmdparse is a command-line interface to CmdLine for Unix shell-scripts.
  16.  It is approximately 1200 lines of C++ code (excluding comments).
  17.  
  18.  
  19.  CmdLine(3C++)
  20.  -------------
  21.  CmdLine is a set of classes to parse command-line arguments.  Unlike
  22.  getopt() and its variants, CmdLine does more than just split up the
  23.  command-line into some canonical form.  CmdLine will actually parse
  24.  the command-line, assigning the appropriate command-line values to
  25.  the corresponding variables, and will verify the command-line syntax
  26.  (and print a usage message if necessary) all in one member function
  27.  call.  Furthermore, many features of CmdLine's parsing behavior are
  28.  configurable at run-time.  These features include the following:
  29.  
  30.      o  Prompting the user for missing arguments.
  31.      o  Allowing keywords (-count=4) and/or options (-c4).
  32.      o  Ignoring bad syntax instead of terminating.
  33.      o  Ignoring upper/lower case on the command-line.
  34.      o  Suppressing the printing of syntax error messages.
  35.      o  Controlling the verboseness of usage messages.
  36.      o  Controlling whether or not options may be processed
  37.           after positional parameters have been seen.
  38.  
  39.  CmdLine also allows for options that take an optional argument, options
  40.  that take a (possibly optional) list of one or more arguments, sticky
  41.  options (options whose argument must reside in the same token as the
  42.  option itself), and options whose argument must reside in a separate
  43.  token from the option itself.
  44.  
  45.  CmdLine consists of a set of C++ classes to parse arguments from an
  46.  input source called a CmdLineArgIter (which is a base class for iterating
  47.  over arguments from an arbitrary input source).  Argument iterators are
  48.  defined for an argv[] array (with or without a corresponding argc), for
  49.  a string of tokens that are separated by a given set of delimiters, and
  50.  for an input-stream.  Users can easily extend CmdLine to parse arguments
  51.  from other input sources simply by creating their own argument iterator
  52.  classes derived from the CmdLineArgIter class defined in <cmdline.h>.
  53.  
  54.  Command-line arguments are themselves objects that contain a specific
  55.  command-line interface, and a function that performs the desired actions
  56.  when its corresponding argument is seen on the command line.  Predefined
  57.  command-line argument types (derived from the abstract class CmdArg in
  58.  <cmdline.h>) exist for boolean, integer, floating-point, character, and
  59.  string arguments, and for lists of integers, floats, and strings.  These
  60.  predefined subclasses of CmdArg may be found in <cmdargs.h>.  Users can
  61.  also create their own command-argument types on the fly by defining and
  62.  implementing an appropriate subclass of the CmdArg class.
  63.  
  64.  Using CmdLine is relatively easy - you need to construct your arguments,
  65.  your command-line, and your argument iterator.  Then all that is left to
  66.  do is call the "parse" member function of your CmdLine object.  The
  67.  following is a simple example:
  68.  
  69.     #include <stdlib.h>
  70.     #include <iostream.h>
  71.     #include <cmdargs.h>
  72.  
  73.     int  main(int argc, char * argv[])
  74.     {
  75.           // Declare arguments
  76.        CmdArgInt  count('c', "count", "number", "number of copies to print.");
  77.        CmdArgBool xflag('x', "xmode", "turn on 'x'-mode.");
  78.        CmdArgChar fdsep('s', "separator", "char", "field-separator to use.");
  79.        CmdArgStr  input("input-file",  "input file to read.");
  80.        CmdArgStrList  output("[output-file ...]",  "where to print output.");
  81.  
  82.           // Declare command object and its argument-iterator
  83.        CmdLine  cmd(*argv, &count, &xflag, &fdsep, &input, &output, NULL);
  84.        CmdArgvIter  arg_iter(--argc, ++argv);
  85.  
  86.           // Initialize arguments to appropriate default values.
  87.        count = 1;
  88.        xflag = 0;
  89.        fdsep = ',';
  90.  
  91.           // Parse arguments
  92.        cmd.parse(arg_iter);
  93.  
  94.           // Print arguments
  95.        cout << "count=" << count << endl ;
  96.        cout << "xflag=" << (xflag ? "ON" : "OFF") << endl ;
  97.        cout << "fdsep='" << (char) fdsep << "'" << endl ;
  98.        cout << "input=\"" << input << "\"" << endl ;
  99.        
  100.        for (int i = 0 ; i < output.count() ; i++) {
  101.           cout << "output[" << i << "]=" << output[i] << endl ;
  102.        }
  103.  
  104.        return  0;
  105.     }
  106.  
  107.  
  108.  The Unix command-line syntax for the above program would be as follows:
  109.  
  110.     Usage: progname [-c number] [-x] [-s char] input-file [output-file ...]
  111.  
  112.     Options/Arguments:
  113.             -c number        number of copies to print.
  114.             -x               turn on 'x'-mode.
  115.             -s char          field-separator to use.
  116.             input-file       input file to read.
  117.             output-file ...  where to print output.
  118.  
  119.  
  120.  The Unix command-line syntax using long-options (keywords) for the above
  121.  program would be as follows:
  122.  
  123.     Usage: progname [--count number] [--xmode] [--separator char]
  124.                     input-file [output-file ...]
  125.  
  126.     Options/Arguments:
  127.             --count number    number of copies to print.
  128.             --xmode           turn on 'x'-mode.
  129.             --separator char  field-separator to use.
  130.             input-file        input file to read.
  131.             output-file ...   where to print output.
  132.  
  133.  If desired, one can set a configuration flag at run-time to allow "+"
  134.  to also be recognized (in addition to "--") as a long-option prefix.
  135.  
  136.  By default, CmdLine allows both options and long-options to appear on the
  137.  command-line. You can instruct CmdLine to disallow one or the other however.
  138.  As an "extra", when options are disallowed, the "-" prefix is assumed to
  139.  denote a long-option instead of an option (hence either "-" or "--" denotes
  140.  a keyword in this case).  Using this feature, CmdLine can be used to supply
  141.  the type of long-option syntax that is now becoming quite popular in the
  142.  Unix world. Using this "new" syntax, the command-line syntax for the above
  143.  command would be the following:
  144.  
  145.     Usage: progname [-count number] [-xmode] [-separator char]
  146.                     input-file [output-file ...]
  147.  
  148.     Options/Arguments:
  149.             -count number    number of copies to print.
  150.             -xmode           turn on 'x'-mode.
  151.             -separator char  field-separator to use.
  152.             input-file       input file to read.
  153.             output-file ...  where to print output.
  154.  
  155.  
  156.  It should be mentioned that, when long-options are used, only a unique
  157.  prefix of the keyword needs to be given (and character-case is ignored).
  158.  Hence, in the above example, "-x", "-X", and "-xm" will match "-xmode".
  159.  
  160.  
  161.  cmdparse(1)
  162.  -----------
  163.  Using "cmdparse" is even easier than using CmdLine. You declare your
  164.  arguments in a string and then you invoke cmdparse with the command
  165.  line of your shell-script and cmdparse will output a script of variable
  166.  settings for you to evaluate.  The following is an example (using the
  167.  same arguments as in our sample program):
  168.  
  169.     #!/bin/sh
  170.     NAME="`/bin/basename $0`"
  171.  
  172.     ARGS='
  173.        ArgInt   count  "[c|count number]"    "number of copies to print."
  174.        ArgBool  xflag  "[x|xmode]"           "turn on x-mode."
  175.        ArgChar  fdsep  "[s|separator char]"  "field-separator to use."
  176.        ArgStr   input  "input-file"          "input file to read."
  177.        ArgStr   output "[output-file ...]"   "where to print output."
  178.     '
  179.  
  180.     if  cmdparse -shell=sh -decls="$ARGS" -- $NAME "$@" > tmp$$
  181.     then
  182.        . tmp$$
  183.        /bin/rm -f tmp$$
  184.     else
  185.        EXITVAL=$?
  186.        /bin/rm -f tmp$$
  187.        exit $EXITVAL
  188.     fi
  189.  
  190.     echo "xflag=" $xflag
  191.     echo "count=" $count
  192.     echo "fdsep=" $fdsep
  193.     echo "input=" $input
  194.     if [ "$output" ] ; then
  195.        echo "output=" $output
  196.     fi
  197.  
  198.  
  199.  Note that you declare the syntax of an argument differently for cmdparse
  200.  than for CmdLine. The syntax for a single argument for cmdparse looks like
  201.  the following:
  202.  
  203.     <arg-type>  <arg-name>  <syntax>  <description>
  204.  
  205.  Where <arg-type> is one of the following:
  206.  
  207.     ArgInt     --  an integer value (or list of values)
  208.     ArgFloat   --  a floating-point value (or list of values)
  209.     ArgChar    --  a character value (or list of values)
  210.     ArgStr     --  a string value (or list of values)
  211.     ArgBool    --  a boolean flag that is turned ON
  212.     ArgClear   --  a boolean flag that is turned OFF
  213.     ArgToggle  --  a boolean flag that is toggled
  214.     ArgUsage   --  print usage and exit
  215.     ArgDummy   --  a dummy argument
  216.  
  217.  If desired, the leading "Arg" portion may be omitted from the type-name.
  218.  
  219.  <arg-name> is simply the name of the variable in your script that you wish
  220.  to contain the resultant value from the command-line.  Any default value
  221.  must be assigned to the variable before invoking cmdparse.
  222.  
  223.  <syntax> and <description> *MUST* be enclosed in either single or double
  224.  quotes! <description> is simply that, the description of the argument.
  225.  
  226.  <syntax> is a little trickier, there are three basic forms of syntax:
  227.  
  228.    1)  "c|keyword"        -- an option the takes no value
  229.    2)  "c|keyword value"  -- an option that takes a value
  230.    3)  "value"            -- a positional parameter
  231.  
  232.  Note that the option-character MUST precede the keyword-name and that
  233.  there must be NO spaces surrounding the '|' in "c|keyword"!
  234.  
  235.  Any "optional" parts of the argument should appear inside square-brackets
  236.  ('[' and ']') and a list of values is denoted by an ellipsis (" ...").
  237.  Most options will be inside of square brackets to reflect the fact that
  238.  they are "optional".
  239.  
  240.  Some example <syntax> strings follow:
  241.  
  242.     "c|keyword"                -- a required option
  243.     "[c|keyword]"              -- an option with no value
  244.     "[c|keyword value]"        -- an option that takes a value
  245.     "[c|keyword [value]]"      -- an option that takes an optional value
  246.     "[c|keyword value ...]"    -- an option that takes 1 or more values
  247.     "[c|keyword [value ...]]"  -- an option that takes 0 or more values
  248.     "value"                    -- a required positional parameter
  249.     "[value]"                  -- an optional positional-parameter
  250.     "[c|keyword] value"        -- a required argument that may be matched
  251.                                   either positionally or by keyword!
  252.  
  253.  
  254.  Further Information
  255.  -------------------
  256.  This is just a brief overview of what the CmdLine package can do. Please
  257.  read the documentation for a more thorough explanation of this products'
  258.  capabilities and limitations!
  259.  
  260.